home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Skunkware 5
/
Skunkware 5.iso
/
man
/
cat.1
/
perlmod.1
< prev
next >
Wrap
Text File
|
1995-07-25
|
26KB
|
595 lines
PPPPEEEERRRRLLLLMMMMOOOODDDD((((1111)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((RRRReeeelllleeeeaaaasssseeee 0000....0000 PPPPaaaattttcccchhhhlllleeeevvvveeeellll 00000000)))) PPPPEEEERRRRLLLLMMMMOOOODDDD((((1111))))
NNNNAAAAMMMMEEEE
perlmod - Perl modules (packages)
DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
PPPPaaaacccckkkkaaaaggggeeeessss
Perl provides a mechanism for alternate namespaces to
protect packages from stomping on each others variables. By
default, a Perl script starts compiling into the package
known as main. You can switch namespaces using the package
declaration. The scope of the package declaration is from
the declaration itself to the end of the enclosing block
(the same scope as the _l_o_c_a_l() operator). Typically it
would be the first declaration in a file to be included by
the require operator. You can switch into a package in more
than one place; it merely influences which symbol table is
used by the compiler for the rest of that block. You can
refer to variables and filehandles in other packages by
prefixing the identifier with the package name and a double
colon: $Package::Variable. If the package name is null, the
main package as assumed. That is, $::sail is equivalent to
$main::sail.
(The old package delimiter was a single quote, but double
colon is now the preferred delimiter, in part because it's
more readable to humans, and in part because it's more
readable to eeeemmmmaaaaccccssss macros. It also makes C++ programmers
feel like they know what's going on.)
Packages may be nested inside other packages:
$OUTER::INNER::var. This implies nothing about the order of
name lookups, however. All symbols are either local to the
current package, or must be fully qualified from the outer
package name down. For instance, there is nowhere within
package OUTER that $INNER::var refers to $OUTER::INNER::var.
It would treat package INNER as a totally separate global
package.
Only identifiers starting with letters (or underscore) are
stored in a package's symbol table. All other symbols are
kept in package main. In addition, the identifiers STDIN,
STDOUT, STDERR, ARGV, ARGVOUT, ENV, INC and SIG are forced
to be in package main, even when used for other purposes
than their built-in one. Note also that, if you have a
package called m, s or y, then you can't use the qualified
form of an identifier since it will be interpreted instead
as a pattern match, a substitution, or a translation.
(Variables beginning with underscore used to be forced into
package main, but we decided it was more useful for package
writers to be able to use leading underscore to indicate
private variables and method names.)
Page 1 (printed 6/30/95)
PPPPEEEERRRRLLLLMMMMOOOODDDD((((1111)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((RRRReeeelllleeeeaaaasssseeee 0000....0000 PPPPaaaattttcccchhhhlllleeeevvvveeeellll 00000000)))) PPPPEEEERRRRLLLLMMMMOOOODDDD((((1111))))
_E_v_a_l()ed strings are compiled in the package in which the
_e_v_a_l() was compiled. (Assignments to $SIG{}, however,
assume the signal handler specified is in the C<main.
package. Qualify the signal handler name if you wish to
have a signal handler in a package.) For an example,
examine _p_e_r_l_d_b._p_l in the Perl library. It initially
switches to the DB package so that the debugger doesn't
interfere with variables in the script you are trying to
debug. At various points, however, it temporarily switches
back to the main package to evaluate various expressions in
the context of the main package (or wherever you came from).
See the _p_e_r_l_d_e_b_u_g manpage.
SSSSyyyymmmmbbbboooollll TTTTaaaabbbblllleeeessss
The symbol table for a package happens to be stored in the
associative array of that name appended with two colons.
The main symbol table's name is thus %main::, or %:: for
short. Likewise the nested package mentioned earlier is
named %OUTER::INNER::.
The value in each entry of the associative array is what you
are referring to when you use the *name notation. In fact,
the following have the same effect, though the first is more
efficient because it does the symbol table lookups at
compile time:
local(*main::foo) = *main::bar; local($main::{'foo'}) =
$main::{'bar'};
You can use this to print out all the variables in a
package, for instance. Here is _d_u_m_p_v_a_r._p_l from the Perl
library:
package dumpvar;
sub main::dumpvar {
($package) = @_;
local(*stab) = eval("*${package}::");
while (($key,$val) = each(%stab)) {
local(*entry) = $val;
if (defined $entry) {
print "\$$key = '$entry'\n";
}
if (defined @entry) {
print "\@$key = (\n";
foreach $num ($[ .. $#entry) {
print " $num\t'",$entry[$num],"'\n";
}
print ")\n";
}
Page 2 (printed 6/30/95)
PPPPEEEERRRRLLLLMMMMOOOODDDD((((1111)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((RRRReeeelllleeeeaaaasssseeee 0000....0000 PPPPaaaattttcccchhhhlllleeeevvvveeeellll 00000000)))) PPPPEEEERRRRLLLLMMMMOOOODDDD((((1111))))
if ($key ne "${package}::" && defined %entry) {
print "\%$key = (\n";
foreach $key (sort keys(%entry)) {
print " $key\t'",$entry{$key},"'\n";
}
print ")\n";
}
}
}
Note that even though the subroutine is compiled in package
dumpvar, the name of the subroutine is qualified so that its
name is inserted into package main.
Assignment to a symbol table entry performs an aliasing
operation, i.e.,
*dick = *richard;
causes variables, subroutines and filehandles accessible via
the identifier richard to also be accessible via the symbol
dick. If you only want to alias a particular variable or
subroutine, you can assign a reference instead:
*dick = \$richard;
makes $richard and $dick the same variable, but leaves
@richard and @dick as separate arrays. Tricky, eh?
PPPPaaaacccckkkkaaaaggggeeee CCCCoooonnnnssssttttrrrruuuuccccttttoooorrrrssss aaaannnndddd DDDDeeeessssttttrrrruuuuccccttttoooorrrrssss
There are two special subroutine definitions that function
as package constructors and destructors. These are the
BEGIN and END routines. The sub is optional for these
routines.
A BEGIN subroutine is executed as soon as possible, that is,
the moment it is completely defined, even before the rest of
the containing file is parsed. You may have multiple BEGIN
blocks within a file--they will execute in order of
definition. Because a BEGIN block executes immediately, it
can pull in definitions of subroutines and such from other
files in time to be visible to the rest of the file.
An END subroutine is executed as late as possible, that is,
when the interpreter is being exited, even if it is exiting
as a result of a _d_i_e() function. (But not if it's is being
blown out of the water by a signal--you have to trap that
yourself (if you can).) You may have multiple END blocks
within a file--they wil execute in reverse order of
definition; that is: last in, first out (LIFO).
Page 3 (printed 6/30/95)
PPPPEEEERRRRLLLLMMMMOOOODDDD((((1111)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((RRRReeeelllleeeeaaaasssseeee 0000....0000 PPPPaaaattttcccchhhhlllleeeevvvveeeellll 00000000)))) PPPPEEEERRRRLLLLMMMMOOOODDDD((((1111))))
Note that when you use the ----nnnn and ----pppp switches to Perl, BEGIN
and END work just as they do in aaaawwwwkkkk, as a degenerate case.
PPPPeeeerrrrllll CCCCllllaaaasssssssseeeessss
There is no special class syntax in Perl 5, but a package
may function as a class if it provides subroutines that
function as methods. Such a package may also derive some of
its methods from another class package by listing the other
package name in its @ISA array. For more on this, see the
_p_e_r_l_o_b_j manpage.
PPPPeeeerrrrllll MMMMoooodddduuuulllleeeessss
In Perl 5, the notion of packages has been extended into the
notion of modules. A module is a package that is defined in
a library file of the same name, and is designed to be
reusable. It may do this by providing a mechanism for
exporting some of its symbols into the symbol table of any
package using it. Or it may function as a class definition
and make its semantics available implicitly through method
calls on the class and its objects, without explicit
exportation of any symbols. Or it can do a little of both.
Perl modules are included by saying
use Module;
or
use Module LIST;
This is exactly equivalent to
BEGIN { require "Module.pm"; import Module; }
or
BEGIN { require "Module.pm"; import Module LIST; }
All Perl module files have the extension ._p_m. use assumes
this so that you don't have to spell out "_M_o_d_u_l_e._p_m" in
quotes. This also helps to differentiate new modules from
old ._p_l and ._p_h files. Module names are also capitalized
unless they're functioning as pragmas, "Pragmas" are in
effect compiler directives, and are sometimes called
"pragmatic modules" (or even "pragmata" if you're a
classicist).
Because the use statement implies a BEGIN block, the
importation of semantics happens at the moment the use
statement is compiled, before the rest of the file is
Page 4 (printed 6/30/95)
PPPPEEEERRRRLLLLMMMMOOOODDDD((((1111)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((RRRReeeelllleeeeaaaasssseeee 0000....0000 PPPPaaaattttcccchhhhlllleeeevvvveeeellll 00000000)))) PPPPEEEERRRRLLLLMMMMOOOODDDD((((1111))))
compiled. This is how it is able to function as a pragma
mechanism, and also how modules are able to declare
subroutines that are then visible as list operators for the
rest of the current file. This will not work if you use
require instead of use. Therefore, if you're planning on
the module altering your namespace, use use; otherwise, use
require. Otherwise you can get into this problem:
require Cwd; # make Cwd:: accessible
$here = Cwd::getcwd();
use Cwd; # import names from Cwd::
$here = getcwd();
require Cwd; # make Cwd:: accessible
$here = getcwd(); # oops! no main::getcwd()
Perl packages may be nested inside other package names, so
we can have package names containing ::. But if we used
that package name directly as a filename it would makes for
unwieldy or impossible filenames on some systems.
Therefore, if a module's name is, say, Text::Soundex, then
its definition is actually found in the library file
_T_e_x_t/_S_o_u_n_d_e_x._p_m.
Perl modules always have a ._p_m file, but there may also be
dynamically linked executables or autoloaded subroutine
definitions associated with the module. If so, these will
be entirely transparent to the user of the module. It is
the responsibility of the ._p_m file to load (or arrange to
autoload) any additional functionality. The POSIX module
happens to do both dynamic loading and autoloading, but the
user can just say use POSIX to get it all.
For more information on writing extension modules, see the
_p_e_r_l_a_p_i manpage and the _p_e_r_l_g_u_t_s manpage.
NNNNOOOOTTTTEEEE
Perl does not enforce private and public parts of its
modules as you may have been used to in other languages like
C++, Ada, or Modula-17. Perl doesn't have an infatuation
with enforced privacy. It would prefer that you stayed out
of its living room because you weren't invited, not because
it has a shotgun.
The module and its user have a contract, part of which is
common law, and part of which is "written". Part of the
common law contract is that a module doesn't pollute any
namespace it wasn't asked to. The written contract for the
module (AKA documentation) may make other provisions. But
then you know when you use RedefineTheWorld that you're
redefining the world and willing to take the consequences.
Page 5 (printed 6/30/95)
PPPPEEEERRRRLLLLMMMMOOOODDDD((((1111)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((RRRReeeelllleeeeaaaasssseeee 0000....0000 PPPPaaaattttcccchhhhlllleeeevvvveeeellll 00000000)))) PPPPEEEERRRRLLLLMMMMOOOODDDD((((1111))))
TTTTHHHHEEEE PPPPEEEERRRRLLLL MMMMOOOODDDDUUUULLLLEEEE LLLLIIIIBBBBRRRRAAAARRRRYYYY
A number of modules are included the the Perl distribution.
These are described below, and all end in ._p_m. You may also
discover files in the library directory that end in either
._p_l or ._p_h. These are old libaries supplied so that old
programs that use them still run. The the ._p_h files made by
hhhh2222pppphhhh will probably end up as extension modules made by hhhh2222xxxxssss.
(Some ._p_h values may already be available through the POSIX
module.) The ppppllll2222ppppmmmm file in the distribution may help in
your conversion, but it's just a mechanical process, so is
far from bullet proof.
PPPPrrrraaaaggggmmmmaaaattttiiiicccc MMMMoooodddduuuulllleeeessss
They work somewhat like pragmas in that they tend to affect
the compilation of your program, and thus will usually only
work well when used within a use, or no. These are locally
scoped, so if an inner BLOCK may countermand any of these by
saying
no integer;
no strict 'refs';
which lasts until the end of that BLOCK.
The following programs are defined (and have their own
documentation).
integer Perl pragma to compute arithmetic in integer
instead of double
less Perl pragma to request less of something from
the compiler
sigtrap Perl pragma to enable stack backtrace on
unexpected signals
strict Perl pragma to restrict unsafe constructs
subs Perl pragma to predeclare sub names
SSSSttttaaaannnnddddaaaarrrrdddd MMMMoooodddduuuulllleeeessss
The following modules are all expacted to behave in a well-
defined manner with respect to namespace pollution because
they use the Exporter module. See their own documentation
for details.
Abbrev create an abbreviation table from a list
AnyDBM_File provide framework for multiple DBMs
Page 6 (printed 6/30/95)
PPPPEEEERRRRLLLLMMMMOOOODDDD((((1111)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((RRRReeeelllleeeeaaaasssseeee 0000....0000 PPPPaaaattttcccchhhhlllleeeevvvveeeellll 00000000)))) PPPPEEEERRRRLLLLMMMMOOOODDDD((((1111))))
AutoLoader load functions only on demand
AutoSplit split a package for autoloading
Basename parse file anme and path from a specification
Benchmark benchmark running times of code
Carp warn or die of errors (from perspective of
caller)
CheckTree run many filetest checks on a tree
Collate compare 8-bit scalar data according to the
current locale
Config access Perl configuration option
Cwd get pathname of current working directory
DynaLoader Dynamically load C libraries into Perl code
English use nice English (or aaaawwwwkkkk) names for ugly
punctuation variables
Env Perl module that imports environment variables
Exporter module to control namespace manipulations
Fcntl load the C Fcntl.h defines
FileHandle supply object methods for filehandles
Find traverse a file tree
Finddepth traverse a directory structure depth-first
Getopt basic and extended _g_e_t_o_p_t(3) processing
MakeMaker generate a Makefile for Perl extension
Open2 open a process for both reading and writing
Open3 open a process for reading, writing, and error
handling
POSIX Perl interface to IEEE 1003.1 namespace
Ping check a host for upness
Socket load the C socket.h defines
Page 7 (printed 6/30/95)
PPPPEEEERRRRLLLLMMMMOOOODDDD((((1111)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((RRRReeeelllleeeeaaaasssseeee 0000....0000 PPPPaaaattttcccchhhhlllleeeevvvveeeellll 00000000)))) PPPPEEEERRRRLLLLMMMMOOOODDDD((((1111))))
EEEExxxxtttteeeennnnssssiiiioooonnnn MMMMoooodddduuuulllleeeessss
Extension modules are written in C (or a mix of Perl and C)
and get dynamically loaded into Perl if and when you need
them. Supported extension modules include the Socket,
Fcntl, and POSIX modules.
The following are popular C extension modules, which while
available at Perl 5.0 release time, do not come not bundled
(at least, not completely) due to their size, volatility, or
simply lack of time for adequate testing and configuration
across the multitude of platforms on which Perl was beta-
tested. You are encouraged to look for them in _a_r_c_h_i_e(1L),
the Perl FAQ or Meta-FAQ, the WWW page, and even their
authors before randomly posting asking for their present
condition and disposition. There's no guarantee that the
names or addresses below have not changed since printing,
and in fact, they probably have!
Curses Written by William Setzer
<_W_i_l_l_i_a_m__S_e_t_z_e_r@_n_c_s_u._e_d_u>, while not included
with the standard distribution, this extension
module ports to most systems. FTP from your
nearest Perl archive site, or try
ftp://ftp.ncsu.edu/pub/math/wsetzer/cursperl5??.tar.gz
It is currently in alpha test, so the name and
ftp location may change.
DBI This is the portable database interface written
by <_T_i_m._B_u_n_c_e@_i_g._c_o._u_k>. This supersedes the
many perl4 ports for database extensions. The
official archive for DBperl extensions is
_f_t_p._d_e_m_o_n._c_o._u_k:/_p_u_b/_p_e_r_l/_d_b. This archive
contains copies of perl4 ports for Ingres,
Oracle, Sybase, Informix, Unify, Postgres, and
Interbase, as well as rdb and shql and other
non-SQL systems.
DB_File Fastest and most restriction-free of the DBM
bindings, this extension module uses the popular
Berkeley DB to _t_i_e() into your hashes. This has
a standardly-distributed man page and dynamic
loading extension module, but you'll have to
fetch the Berkeley code yourself. See the
_D_B__F_i_l_e manpage for where.
Sx This extension module is a front to the Athena
and Xlib libraries for Perl GUI progamming,
originally written by by Dominic Giampaolo
<_d_b_g@_s_g_i._c_o_m>, then and rewritten for Sx by
Page 8 (printed 6/30/95)
PPPPEEEERRRRLLLLMMMMOOOODDDD((((1111)))) UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((RRRReeeelllleeeeaaaasssseeee 0000....0000 PPPPaaaattttcccchhhhlllleeeevvvveeeellll 00000000)))) PPPPEEEERRRRLLLLMMMMOOOODDDD((((1111))))
Frederic Chauveau <_f_m_c@_p_a_s_t_e_u_r._f_r>. It's
available for FTP from
ftp.pasteur.fr:/pub/Perl/Sx.tar.gz
Tk This extension module is an object-oriented
Perl5 binding to the popular tcl/tk X11 package.
However, you need know no TCL to use it! It was
written by Malcolm Beattie
<_m_b_e_a_t_t_i_e@_s_a_b_l_e._o_x._a_c._u_k>. If you are unable to
locate it using _a_r_c_h_i_e(1L) or a similar tool,
you may try retrieving it from /_p_r_i_v_a_t_e/_T_k-
_o_c_t_o_b_e_r._t_a_r._g_z from Malcolm's machine listed
above.
Page 9 (printed 6/30/95)